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Abstract 

We give a beginner-oriented introduction to Isabelle/jEdit, providing motivation for 
using it as well as pointing at some differences to the traditional Proof General interface 
and current limitations. 

1 Introduction 

Before starting, let us clarify our goals. This document is intended as a short introduction to 
Isabelle/jEdit (as shipped with Isabelle2012) from a new user's perspective. We highlight 
some differences to Proof General and common pitfalls for new users (mostly issues that have 
been collected from the Isabelle mailing lists) . We do not give any technical or implementation 
details (for such, refer to [1, 3, 5, 4, 2] and the Isabelle documentation). Moreover, our intended 
audience are newcomers to Isabelle/jEdit (that is, we have nothing to say that people could 
not easily find out on their own, but hope to save some people some time). 




In paragraphs like this, we point out differences to Proof General. Thus, users who are not familiar 
with Proof General, may safely skip them. 



/j\ Points that may need special attention are marked like this. 

We use the following conventions: When indicating a menu like A— >B— >C we mean: "Click 
on submenu C in submenu B of menu A." When indicating keyboard shortcuts like C-s we mean: 
"Keep key C pressed while pressing key s." Here, C refers to the control key (usually labeled 
with Ctrl on PC keyboards; on Mac OS this is actually command). 

The remainder is structured as follows: First, in Section 2, we argue why we think that Isa- 
belle/jEdit is more suitable as a user interface to Isabelle than the traditional Proof General, 
but also give some current limitations. Then, in Section 3, we explain how to obtain and start 
Isabelle/jEdit and give an example walkthrough. The next section (Section 4) is concerned 
with some typical use cases. Finally, we conclude in Section 5. 

2 Why Isabelle/jEdit is Awesome 

The most important point (in our opinion) is that Isabelle/jEdit (or rather the technology that 
makes it possible to use the editor jEdit as an interface to the proof assistant Isabelle) provides 
an interaction model that is broadly known and used nowadays (e.g., in word processors and 
integrated development environments for programming languages). Lets call it the document 
model. The user sees and freely edits a document and all the heavy machinery of Isabelle 
asynchronously runs in the background and supplies source text with semantic information 
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that is again presented in ways people are used to nowadays (highlighting, hyperlinks, tooltips, 
wavy underlines, etc.). 

The traditional interaction model, in contrast, is more like a command-line interface, we 
sequentially enter commands (one at a time) and wait for the corresponding output. Since this 
would be exceedingly tedious whenever we wanted to change something we entered very early 
(essentially, we have to enter everything again), this kind of interaction is usually combined 
with source text. Such that instead of typing everything again, we just tell the system which 
part of the source text has to be reloaded. However, in order for this to work, we need some 
kind of locked region (the part of the source text that has already been processed) which we 
are not allowed to edit. Or alternatively, reload everything after each change. 

tin Proof General there is a visible locked region that can be extended or reduced using keyboard 
shortcuts or corresponding menu buttons. Mostly this works just fine, but if you are unfortunate 
the locked region may become out of sync with the underlying prover process. In contrast, Isabelle/ 
jEdit allows to freely edit a document at any position. 

At this point you may wonder: "What's the big deal about the document model?" Since 
it may seem that the only difference to the traditional model (lets call it the sequential model) 
is that we do not have to manage a locked region manually. Well, the main point is that the 
sequential model is inherently sequential, whereas the document model offers plenty of space 
for parallelization. Thus, Isabelle/jEdit does not only provide a more modern (and for many 
potential users more familiar) user interface but additionally facilitates (again, the real reason 
is rather the underlying technology) to seamlessly make use of multi-core architectures. 

Having said this (and that is the reason why Isabelle/jEdit is indeed awesome), bear in mind 
that we are talking about brand new technology here (which was moreover mostly developed 
by a single person; cf. the references). Hence, it comes as no surprise that there are still some 
small quirks and deficiencies. Most notably, there is no real tutorial for Isabelle/jEdit and most 
menus that where available in the traditional interface are still missing. We will have more to 
say about this in Section 4. Nevertheless, Isabelle/jEdit is ready for production use now. 

3 Get Rolling 

Before we can use Isabelle/jEdit, we have to download it. Since it is contained in the official 
Isabelle release, we download that from: 

http : / / isabelle . in . turn . de or http : //www . cl . cam . ac . uk/research/hvg/Isabelle/ 
or http : / /mirror . cse . unsw . edu . au/ pub/ isabelle/ 

The correct version for your operating system and architecture should be provided by the big 
green button and can be installed to an arbitrary directory ISABELLE_HDME. 

/j\ Do not try to combine arbitrary versions of PolyML, Isabelle, Scala, Java, and jEdit if you want to 
avoid problems. Everything you need is packaged in the Isabelle bundle. 

To start Isabelle/jEdit from a command line (e.g., under Linux) use (something similar to) 

ISABELLE_HOME/bin/ isabelle jedit 

(Under Mac OS click on the Isabelle2012.app icon and then select Isabelle/jEdit instead of the 
default Proof General. Under Windows click on Isabelle2012.exe.) 
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jEdit- Scratch.thy 

File F.dit Search Markers Fojding View LJtilities Macros F^lugins Help 
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□ Scratch.thy [~/Documents/Papers/jedit/) 



Check J [ Cancel ] | Ready | default [HOD 



README | Thscry Status | System Log 



nd.e 



Output 



Prover Session 
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Figure 1: Isabelle /jEdit when first started. 



In Figure 1 you see how Isabelle/jEdit presents itself after being started the first time (we 
just reduced the initial window size in favor of readability). On the top half we have the main 
buffer, this is where our source text is shown and editing takes place. At the bottom of the lower 
half we have (among others) buttons Output and Prover Session which determine the content 
of the panel directly above of them. By default Prover Session is selected. When selecting 
Output the panel shows the output buffer, this is where messages from the current command 
are to be found, where the current command is determined by the cursor position in the main 
buffer (i.e., by default the output buffer shows the message(s) corresponding to the command 
on which the cursor is positioned). 

/j\ Under Prover Session we have a panel containing the tabs README and Theory Status. The former 
is of general interest (since it lists some limitations and workarounds as well as known problems) and 
the latter can always be consulted to check whether Isabelle/jEdit agrees with you on what files are 
loaded (and how much of them), where problems are indicated in red. 



/j\ Prover Session also contains a drop-down list where it seems to be possible to select a certain logic 
image (where the default is default (HOL)). This does, however, not work at the moment. Instead you 
have to restart Isabelle/jEdit like 

isabelle jedit -1 Image 

where Image is the name of the desired logic image and you have to make sure that the selection is 
default (HOL) (otherwise, the -1 flag will be ignored). 



3 



Getting Started with Isabelle/jEdit 



C. Sternagel 



To start using Isabelle/jEdit let us formalize a simple fact about lists. Before we can do so, 
we need to start a theory (which is Isabelle parlance for a source file that bundles definitions 
and facts under a common name). We start by typing "theory Test imports Main begin" 
into the main buffer, which tells the system to start a theory with name Test on top of the 
theory named Main, the default starting point for Isabelle theories (i.e., providing some kind 
of "standard library" of definitions and facts). At this point you may notice an error message 
in the output buffer (which is additionally stressed by showing a prohibition sign in the left 
margin as well as wavy underlining the word "theory" in the input. 

Bad file name "Scratch. thy" for theory "Test" 

This just happened because the default file name for theories is Scratch. thy and can easily be 
resolved by saving (either File— J'Save or C-s) the current file under the name Test .thy. 

/j\ A theory with name Name has to reside in a file with name Name . thy. The Isabelle convention is 
to capitalize theory names and separate words by underscores, e.g., Complete_Partial_Order rather 
than completePartialOrder, complete_partial_order, etc. 

Now, let us come back to the announced fact about lists: when we combine the head and 
the tail of a non-empty list, we obtain the same list again. To make it a bit more interesting 
(and informative), we define our own functions for computing the head and the tail of a list as 
follows: 

fun head :: "'a list => 'a" where "head (x # xs) = x" 

fun tail :: "'a list => 'a list" where "tail (x # xs) = xs" 

There are already a few things to note here. When defining head, a warning occurs (which is 
additionally stressed by showing a light bulb sign in the left margin as well as wavy underlining 
the word "fun" in the input) 



Missing patterns in 


function definition: 


head [] = undefined 





which tells us that our function is not defined on input [] . This is not an error but just a 
warning, since we could intend our function to be undefined in this case (as we indeed do). A 
similar warning is issued for tail. Further note that the status of an identifier is indicated by 
its color: free variables are rendered blue, bound variables green, defined constants black, etc. 
Moreover, many entities allow to jump to their definition by holding C pressed while left-clicking 
on them with the mouse. For head and tail this means that we end up in the line containing 
the corresponding fun keyword (even if that line would be part of a different file). We can test 
this behavior by C-left-clicking # in the definition of head which brings us to the theory List of 
Isabelle's standard library. More concretely, to the line where the list datatype is defined (since 
# refers to one of the constructors of the list datatype). The fastest way of going back is C-' 
(control together with backtick, not to be confused with a single quote) or View— ^Go to Recent 
Buffer. 

Now we prove our little lemma (note that at this point head and tail are printed black, 
since they are defined constants now): 

lemma "~(xs = [] ) ==> head xs # tail xs = xs" 
by (cases xs) simp_all 

We finish our small theory by adding end at the end of the file. 
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4 How To . . . 

In this section we give several typical use cases of things that you might want (or have) to do 
inside Isabelle/jEdit. It is organized by typical user questions/statements. 

4.1 How can I use fancy mathematical symbols? 

This is really easy and convenient thanks to the code completion facility of the SideKick plu- 
gin. By default, code completion is active (you can change the corresponding settings at Plu- 
gins— 7>Plugin Options. .. — >SideKick) and works as follows: you just enter what you mean in plain 
ASCII and if available the system offers you a popup with alternative choices. If you want to 
close the popup, just keep on typing (if you are at the end of a word just enter a space) or 
press ESC. If you want to choose an alternative, navigate through the popup using the arrow 
keys (or the mouse) and press ENTER when you are satisfied. E.g., after typing ==> (two equal 
signs followed by a greater than) a popup will show up containing =$■. Many symbols also 
have names that are close to the usual I^T^X names, e.g., type f orall to obtain V, exists to 
obtain 3, etc. Often, you do not even have to enter the full name, a prefix is enough, e.g., after 
typing f o you will obtain a choice between the keyword for, the symbol V, and the symbol 4. 

tin Proof General we had to type \<f orall> (and this is still how special symbols are actually stored 
in your theory files) to obtain V (and woe betide you, in case of a typo ... we had to start afresh). 
Some versions of Proof General allow the shorter \f orall. 

4.2 There is nothing wrong in my file, but jEdit complains! 

It can happen that the parser (which avoids to reparse the whole file for obvious efficiency 
reasons) of Isabelle/jEdit gets confused by your editing, resulting in a wrong error message. In 
such a case, the usual workaround is to select a chunk of text surrounding your edit and then 
cut and paste it (thereby forcing Isabelle/jEdit to reparse the whole chunk). Usually it is a 
good idea to cut and paste a "complete" chunk of text, e.g., a comment including (* and *), 
a whole lemma statement (not necessarily the corresponding proof), etc. 

4.3 Where have all the menus gone? 

In Proof General many settings of Isabelle and diagnostic commands could be configured and 
started via menus. This is currently not supported in Isabelle/jEdit. The workaround is to 
explicitly change a setting or start a diagnostic command from your main buffer. This is not 
as tedious as it may sound due to code completion (e.g., a popup containing f ind_theorems 
already occurs after typing fi). The bigger drawback is that we have to memorize all the 
available settings and commands (since otherwise you do not know what to type). To this end, 
the Isar reference manual (isabelle doc isar-ref ) is very helpful, which contains descriptions 
(and names) of all available settings and commands. For configuration options like show_types 
you additionally have to know how to set them from inside the main buffer, which works by 
typing something like: 

declare [ [show_types , show_sorts=f alse , ...]] 

Arguably the most frequent diagnostic commands are (in arbitrary order): 
• f ind_theorems for finding theorems 
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• print_cases for printing the available cases inside an induction or case analysis 

• sledgehammer to invoke sledgehammer on the current goal (a nice feature is that after 
sledgehammer reports a metis command in the output buffer, you can just click on it to 
substitute it for the sledgehammer in your main buffer) 

• nitpick and quickcheck for finding a counter example to the current goal 

5 Conclusions 

In total, we just summarized some of the points that have already been discussed on the 
Isabelle mailing lists (or elsewhere). Nevertheless, we hope that this short and beginner-oriented 
introduction may help potential new users out there to get up and running faster than they 
would have without this document. 

A final point for considering to use Isabelle /jEdit instead of Proof General is the following 
(it is rather practical than ideological): 




The Isabelle developers do no longer maintain Proof General for Isabelle and until now nobody else 
stepped forward to do so. 
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